Filtering File Objects

The process of choosing which files, folders, and volumes to display in the browser list or the pop-up menus is known as object filtering . If your application needs simple, straightforward object filtering, pass a pointer to a structure of type NavTypeList to the appropriate Navigation Services function. If you desire more specific filtering, Navigation Services lets you implement an application-defined filter function. Filter functions give you more control over what can and can't be displayed; for example, your function can filter out non-HFS objects. You can use both a NavTypeList structure and a filter function if you wish, but keep in mind that your filter function is directly affected by the NavTypeList structure. For example, if the NavTypeList structure contains only 'TEXT' and 'PICT' types, only files of those types are passed into your filter function. Also, your filter function can filter out file types that are defined in your NavTypeList structure. Make sure you don't accidentally exclude items you wish to display.

Navigation Services tells you which dialog box control was used for each call to your filter function, so you can implement different criteria for each control. You might choose to limit the Desktop button to displaying specific volumes, for example, or to restrict navigation through the Location pop-up menu. The default location and selections can also be filtered. For more information, see Filtering File Objects .

The function NavGetFile displays a Show pop-up menu that lists your application's native types as well as translatable file types. If the user chooses a translatable file type, Navigation Services ignores your NavTypeList structure and responds only to your filter function. For more information on the Show pop-up menu, see Providing File Opening Options .

The function NavPutFile displays a Format pop-up menu that displays the save format options, the application's native types, and the file types that can translated. This pop-up menu selection does not affect filtering of the browser list; it determines the file format used to save the final document.

Object Filtering Scenarios

This section gives some examples to help explain how filtering works in the Show pop-up menu. For purposes of illustration, assume the following:

The application Sampler can open files of type 'TEXT ' and 'PICT '.
Sampler passes to the NavGetFile function a structure of type NavTypeList that contains these two file types as well as Sampler's application signature.
Sampler implements a kind string for each of these native file types.
Sampler specifies the kNavDontAddTranslateItems constant in the dialogOptions field in the structure of type NavDialogOptions that it passes in the dialogOptions parameter of the NavGetFile function.

The Show pop-up menu contains the items shown in Figure 22 . Note that the menu does not contain a translatable file section.

Figure 22 A Show pop-up menu without a translatable file section

The user can select the All Readable Documents command to display all of Sampler's native file types at once.

If Sampler specifies the kNavNoTypePopup constant in the dialogOptions field, no Show pop-up menu appears and Sampler's NavTypeList structure and filter function determine any filtering. If Sampler passes NULL to the NavGetFile function in place of a reference to the NavTypeList structure, the Show pop-up menu won't appear (regardless of the dialog options) and Sampler's application-defined filter function is the only determining filter. If Sampler doesn't provide a filter function, all files are displayed.

Note

Under Navigation Services 1.1, if your application passes a NavTypeList structure to the NavGetFile function and specifies the kNavNoTypePopup constant, Navigation Services will display all files of the types described in the NavTypeList structure, even if they were created by a different application.

In the next example, assume the following:

The application Portal can open files of type 'TEXT ', 'PICT ', and 'MooV '.
Portal has a structure of type NavTypeList containing these three file types as well as its application signature.
Portal provides kind strings for each of these native file types.
Portal supplies the kNavAllFilesInPopup constant in the dialogOptions field of the NavDialogOptions structure. This adds the All Documents item at the bottom of the menu.
Portal does not supply the kNavDontAddTranslateItems constant in the dialogOptions field of the NavDialogOptions structure.

In this case, the Show pop-up menu appears as shown in Figure 23 .

Figure 23 A Show pop-up menu with a translatable files section

The third section of the Show menu shows file types that the Translation Manager can translate into one of Portal's three native file types.

Under Navigation Services 1.1, if the user chooses the All Readable Documents menu item, Navigation Services displays all native and translatable file types, regardless of which application created them. If the user chooses the All Documents menu item, the browser list shows all file types, regardless of whether Portal has identified them as translatable or not.

Refreshing the Browser List

If your application needs to refresh the list of file objects in the browser before exiting a Navigation Services function such as NavGetFile , follow these steps:

Supply the kNavCtlGetLocation constant in the selector parameter of the function NavCustomControl to obtain the current location.
Pass the current location in the parms parameter of NavCustomControl and supply the kNavCtlSetLocation constant in the selector parameter of NavCustomControl .

Getting and setting the current location causes Navigation Services to rebuild the browser list. For more information on these constants, see Custom Control Setting Constants.